using System;
using System.Threading;
using System.Threading.Tasks;
using WCS.Infrastructure.Attr;
using WCS.Infrastructure.Dto.Request.Ai;
using WCS.Infrastructure.Dto.Response.Common;

namespace WCS.Service.Interface
{
    /// <summary>
    /// 文件说明：混元 AI 对话服务接口
    /// 作用：定义与外部混元 chat/completions 的调用契约
    /// 作者：系统自动生成
    /// 日期：2025-11-19
    /// </summary>
    [Provider]
    public interface IHunyuanService
    {
        /// <summary>
        /// 发送对话请求至混元，并返回统一结果
        /// </summary>
        /// <param name="dto">对话请求参数</param>
        /// <param name="ct">取消令牌</param>
        /// <returns>统一返回对象，成功 code=0，data 为混元响应</returns>
        /// <exception cref="Exception">网络错误或解析错误时抛出（由全局异常中间件兜底）</exception>
        Task<ApiResult> ChatAsync(ChatRequestDto dto, CancellationToken ct = default);

        /// <summary>
        /// 发送流式对话请求至混元，并返回原始 HTTP 响应以便控制器直接转发 SSE。
        /// </summary>
        /// <param name="dto">对话请求参数，需包含 stream=true</param>
        /// <param name="ct">取消令牌</param>
        /// <returns>外部服务的原始响应对象（内容类型 text/event-stream）</returns>
        /// <exception cref="Exception">网络错误时抛出（由全局异常中间件兜底）</exception>
        Task<System.Net.Http.HttpResponseMessage> ChatStreamRawAsync(ChatRequestDto dto, CancellationToken ct = default);
    }
}